 /*
 * File:   thread.h
 * Author: shaman
 *
 * Created on 25 Февраль 2009 г., 15:18

       1. Принцип работы библиотеки:
   Все потоки постоянно находятся внутри единой структуры (циклической двунаправленной очереди), при этом
каждый поток имеет флаг определяющий его активность (active), если этот флаг сброшен, то на данный поток управление
передаваться не будет. Так же каждый поток имеет флаг удаления (delete), по умолчанию он сброшен, однако если данный
флаг окажется установленным, то при попытке передачи на него управления, он будет удалён. Важно отметить, что
все потоки являются равноправными. А при передачи управления следующему потоку происходит поиск первого активного
потока и активируется его контекст.

	2. Система блокирования ресурсов и разграничения доступа:
   
           2.1 Функции lock и unlock
   При вызове функции thread_lock происходит регистрация пераметра lock_index за данным потоком и затем любой поток
попытавшийся заблокировать этот же ресурс будет заблокирован (locked) до тех пор, пока из потока занявшего
ресурс не будет вызвана функция thread_unlock, которая разблокирует ресурс с индексом lock и активизирует все потоки
заблокированные ранее при попытке доступа к данному ресурсу (active).

           2.2 Функции wait и signal
   При вызове функции signal_wait происходит добавление потока в очередь потоков ожидающих появления сигнала от
функции thread_signal. При вызове thread_signal происходит разбллокирование потока оказавшегося первым в очереди
заблокированных потоков с данным индексом, оставшиеся потоки продолжают ожидать следующего вызова сигнал.
 */

#ifndef _THREAD_H
#define	_THREAD_H

//Подключаем заголовочный файл конфигурации
#include "config.h" 

//======================================================================================
//desc:
//  Функция инициализирует работу библиотеки и создаёт первый активный поток

//params:
//  func - функция для которой создаётся поток
//  arg  - аргумент пердаваемый функции

//return:
//  Возвращает код ошибки, 0 - ошибки нет (см. документацию "Коды ошибок и их описание.")
int thread_init (thread_func_t func, void* arg);

//======================================================================================
//desc:
//  Функция создаёт поток (создаваемый поток попадает в очередь активных)

//params:
//  func - функция которая выносится в отдельный поток
//  arg  - параметр передаваемый функции

//return:
//  Если действие завершилось успешно возвращается 0, иначе - (-1).
int thread_create (thread_func_t func, void* arg);

//======================================================================================
//desc:
//  Функция предназначена для передачи управления на другой поток.
//  !!!Реализация библиотеки, не требует её постоянного принудительного вызова!!!

//return:
//  Если действие завершилось успешно возвращается 0, иначе - (-1).
int thread_yield (void);

//======================================================================================
//desc:
//  Функция блокирует ресурс с индексом lock, и при попытке др. потока
//заблокировать ресурс с этим же индексом, его поток, будет перемещён в
//очередь неактивных потоков.

//params:
//  lock - блокируемый индекс

//return:
//  Вернёт 0 при успешном выполнении и -1 в случае ошибки
int thread_lock (unsigned int lock);

//======================================================================================
//desc:
//  Функция разблокирует ресурс с индексом lock.

//return:
//  Вернёт 0 при успешном выполнении и -1 в случае ошибки
int thread_unlock (unsigned int lock);


//======================================================================================
//decs:
//  функция останавливает поток, до получения сигнала от singal

//return:
//  Вернёт 0 при успешном выполнении и -1 в случае ошибки
int thread_wait (unsigned int signal);

//======================================================================================
//decs:
//  Функция посылает сингал

//return:
//  Вернёт 0 при успешном выполнении и -1 в случае ошибки
int thread_signal (unsigned int signal);

#endif	/* _THREAD_H */

